💡 Motivation and Context

Follow-ups from the #739 review — approved to unblock, but three considerations went unaddressed before merge:

1. Nested attribute values weren't snapshotted — _SeriesState shallow-copied the attributes dict, so mutating a nested list/dict after count() rewrote an already-keyed series' attributes on the wire. Attributes are now deep-copied at capture (with a shallow fallback for un-copyable exotic values, keeping the no-throw guarantee).

2. Retry policy was fixed-cadence with an off-by-one drop — the window was retried at the base flush interval and dropped on the fourth failure while the release note said three. Failed flushes now back off exponentially (2× per consecutive failure, capped at 64× the flush interval — the same ceiling the shared JS logs implementation uses) and the window is dropped after exactly _MAX_CONSECUTIVE_SEND_FAILURES = 8 consecutive failures (~21 min of outage coverage at the default 10s interval). The series cap still bounds buffered memory throughout. Browser/Node parity for this policy is a follow-up on the JS side.

3. Lazy metrics init escaped the client's no-throw contract — Client("phc_...", metrics={"resource_attributes": "bad"}) made the first client.metrics.count() raise AttributeError into application code. Nested config is now validated field-by-field (non-dict config/resource_attributes, non-numeric flush_interval, non-integer max_series_per_flush, non-callable before_send) and degrades to defaults with a warning; the client.metrics property additionally falls back to a default-config instance if construction fails (raising only in debug mode, matching no_throw).

💚 How did you test it?

TDD — new tests written first and confirmed failing against the merged code, then made green:

• test_nested_attribute_values_snapshot_at_capture — mutates a list attribute after capture, asserts the two series keep distinct wire attributes.
• test_failed_flushes_back_off_exponentially_capped — pins the [2, 4, 8, 16, 32, 64, 64]× delay schedule and the reset-on-success.
• test_window_survives_failures_until_the_drop_limit / updated test_window_dropped_after_consecutive_failures — pin the drop-at-exactly-8 boundary from both sides.
• test_hostile_metrics_config_does_not_raise_and_still_records — parameterized over five hostile configs, asserts the full public call chain records with defaults.

Full local validation: pytest posthog/test (1207 passed; the pre-existing test_integration_stop_reason failure reproduces on a clean checkout), ruff check/format --check, mypy | mypy-baseline filter (clean), python -W error -c "import posthog", make public_api_check (no public surface change).

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran sampo add to generate a changeset file (hand-written changeset, patch bump)

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• PostHog Code (Claude) session directed by @DanielVisca; work scoped to the three unresolved review threads on feat(metrics): add posthog.metrics count/gauge/histogram API (alpha) #739.
• Chose deep-snapshot over restricting attributes to scalars (the reviewer offered both): Python's array-attribute support is already released and tested, so snapshotting fixes the aliasing bug without a behavior break.
• Chose 8 attempts × capped-64× backoff over keeping the 3-attempt budget: with backoff spacing the retries out, a small budget would drop data ~2 minutes into an outage; 8 attempts covers ~21 minutes while the series cap bounds memory.

Created with PostHog Code